home *** CD-ROM | disk | FTP | other *** search
/ Aminet 21 / Aminet 21 (1997)(GTI - Schatztruhe)[!][Oct 1997].iso / Aminet / util / libs / DigNet.lha / dignet / developer / dignet.doc
Text File  |  1997-08-23  |  50KB  |  2,021 lines
  1. TABLE OF CONTENTS
  2.  
  3. dignet.library/---notes---
  4. dignet.library/---resourcetracking---
  5. dignet.library/AbortNet
  6. dignet.library/AllocNet
  7. dignet.library/CallModemDP
  8. dignet.library/CallModemDT
  9. dignet.library/CaptureTextEnd
  10. dignet.library/CaptureTextStart
  11. dignet.library/ConverseText
  12. dignet.library/ConvertModemString
  13. dignet.library/FlushNet
  14. dignet.library/FreeNet
  15. dignet.library/GetBaudrate
  16. dignet.library/GetBitwidth
  17. dignet.library/GetCurrentDevice
  18. dignet.library/GetCurrentUnit
  19. dignet.library/GetHandshake
  20. dignet.library/GetIOmsg
  21. dignet.library/GetModemStatus
  22. dignet.library/GetNetport
  23. dignet.library/GetParity
  24. dignet.library/GetStopbits
  25. dignet.library/HangupModem
  26. dignet.library/InitIOEXT
  27. dignet.library/InitModem
  28. dignet.library/ObtainNet
  29. dignet.library/ParseConnect
  30. dignet.library/QueryNet
  31. dignet.library/ReadIOEXT
  32. dignet.library/ReadNet
  33. dignet.library/ReadString
  34. dignet.library/SetBaud
  35. dignet.library/SetBitwidth
  36. dignet.library/SetDefault
  37. dignet.library/SetHandshake
  38. dignet.library/SetParity
  39. dignet.library/SetStopbits
  40. dignet.library/StopWaiting
  41. dignet.library/Timeout
  42. dignet.library/WaitModem
  43. dignet.library/WaitText
  44. dignet.library/WriteNet
  45. dignet.library/WriteString
  46. dignet.library/RTAbort
  47. dignet.library/RTCheck
  48. dignet.library/RTFlush
  49. dignet.library/RTHighestID
  50. dignet.library/RTKillNet
  51. dignet.library/RTNetInfo
  52. dignet.library/RTNumberofNets
  53.  
  54. dignet.library/---notes---                         dignet.library/---notes---
  55.  
  56.   From version 4 you are not allowed to open the library from a task, only a
  57.   process. This shouldn't cause any problems with normal usage (only lowlevel
  58.   programs are tasks such as devices etc.). The reason is that the arexx host
  59.   capability is created as a subprocess of the process calling the library.
  60.  
  61.   From AREXX you should NOT open this as an arewxx library. You should in
  62.   fact use this library as an host which means that you address the port
  63.   (DIGNET) just like with for instance RexxMast and other arexx capable
  64.   applications. This may seem to be confusing, but look at the provided demo
  65.   script to see how.
  66.  
  67.   All AREXX comands are case-insensitive.
  68.  
  69. dignet.library/---resourcetracking---   dignet.library/---resourcetracking---
  70.  
  71.   In dignet.library version 3+ you will find special functions for resource
  72.   tracking. All functions that has something to do with resource tracking
  73.   begin with the letters RT. They are not within the safty call procedure as
  74.   the other functions are so you should be very careful when using those.
  75.  
  76.   You can now create your own RT tools for the dignet.library.
  77.  
  78.   NOTE:
  79.  
  80.   You should not use these functions as an replacement for the ordinary
  81.   functions. The arguments is NOT compatible. They should only be used for
  82.   debug reasons. If you don't know what you're doing you are more or less
  83.   guaranteed a system crash. You have been warned. As the other functions are
  84.   very much "protected" the RT functions are much more sensitive.
  85.  
  86.   PROCEDURE:
  87.  
  88.   You should always use the RTCheck() function first. If this function return
  89.   FALSE there is a mismatch in the resource list and alloclist. The system is
  90.   unstable.
  91.  
  92.   If RTCheck() return TRUE you should check how many nets are available with
  93.   the RTNumberOfNets(). If null exit. Alternativly and recommended you could
  94.   use the RTHighestID() to find the highest net ID used.
  95.  
  96.   Then you should use the RTNetInfo() and check parse the list until you get
  97.   to the highest ID (maximum 1024). If the DNRT_TASKSTATUS is FALSE you have
  98.   resources that you can free.
  99.  
  100.   You can then use RTKillNet() on the current ID number or dump information
  101.   to a console or file.
  102.  
  103.   You can use RTAbortNet(), RTFlushNet and RTNetInfo() on a healthy task.
  104.  
  105. dignet.library/AbortNet                               dignet.library/AbortNet
  106.  
  107. NAME
  108.     AbortNet -- aborts the device's current IO action
  109.  
  110. SYNOPSIS
  111.  
  112.     error=AbortNet(net)
  113.                    a0
  114.  
  115.     ULONG AbortNet(APTR);
  116.  
  117.  
  118. FUNCTION
  119.     This function will abort the iorequests at the device. All iorequests are
  120.     stopped immediatly. Read the serial.doc for more information on how this
  121.     works.
  122.  
  123.     From version 3 this function doesn't flush the net any longer. Use the
  124.     FlushNet() function for that.
  125.  
  126. INPUTS
  127.     net - ptr. to a valid net structure
  128.  
  129. RESULTS 
  130.     error - return null or an errorcode
  131.  
  132. NOTES
  133.     From version 3 this function no longer flushes the net.
  134.  
  135. AREXX
  136.     ABORTNET '"'<net>'"'
  137.  
  138. EXAMPLE
  139.     
  140. BUGS
  141.     
  142. SEE ALSO
  143.     FlushNet(), serial.doc
  144.  
  145. dignet.library/AllocNet                               dignet.library/AllocNet
  146.  
  147. NAME
  148.     AllocNet -- Allocates a private structure to use with the other functions
  149.  
  150. SYNOPSIS
  151.  
  152.     net=AllocNet(devicename,unit)
  153.                  a1         d0
  154.  
  155.     APTR AllocNet(STRPTR,UWORD);
  156.  
  157.  
  158. FUNCTION
  159.     To use any of the functions in this library you need to allocate a net
  160.     structure. This structure is private. The structure information is needed
  161.     for the other functions to know where and what to read/write. It also
  162.     allocates memory to use with IOEXT, message structures and so on.
  163.     Additionally the device get flushed and aborted at startup to make a clean
  164.     start for user. When this function returns true you are ready to use the
  165.     device (Note: opposite of a OpenDevice() call).
  166.  
  167.     CHANGES: From version 3 of this library this function no longer inits the
  168.     device with a default setting (see SetDefault()). That means it use the
  169.     setup you have defined in the serial preference program on your system.
  170.     However if you find it difficult to configure it correctly you could use
  171.     the SetDefault() function to set the device to a "safe" setup which
  172.     supports highspeed and 8-bits transfers.
  173.  
  174. INPUTS
  175.     devicename - ptr. to the device name you want to open [0]
  176.     unit - unit number
  177.  
  178. RESULTS 
  179.     net - ptr. to a private structure or NULL if any errors.
  180.  
  181. NOTES
  182.     NOTE: Devices returns NULL when succeeded. This library function will not
  183.     reflect this result. It will return NULL only if a failure occured such
  184.     as out of memory or the port couldn't be created or the device couldn't
  185.     be opened. There is currently no way within the library to find the exact
  186.     cause of the problem.
  187.  
  188.     However, most other functions in this library returns NULL when things
  189.     went well since they reflect the io_error field. Keep this in mind!
  190.  
  191.     NOTE WELL: Max length of taskname and device name is 127 (including the
  192.     null byte termination). The names are copied to a private buffer.
  193.  
  194.     Max open nets is currently 1024 which really is more than enough (not to
  195.     sound like Bill Gates, but a device can only have 256 open units and you
  196.     would need to open 4 devices and use all the units to exceed the max
  197.     limit of this library - just to be on the safe side..)
  198.  
  199. AREXX
  200.     ALLOCNET "<devicename>" <unitnumber>
  201.     RESULT=NetNumber (not address)
  202.  
  203. EXAMPLE
  204.  
  205.     Net=AllocNet("serial.device",0)
  206.  
  207. or
  208.     move.l    DignetBase,a6        ;library base in a6
  209.  
  210.     lea    DeviceName,a0        ;device name in a0
  211.     moveq    #0,d0            ;unit number in d0
  212.     jsr    _LVOAllocNet(a6)    ;call function
  213.  
  214.     move.l    d0,Net            ;store pointer
  215.     beq    Error            ;if null go to error handling
  216.  
  217. BUGS
  218.     An exact cause of an error should be implemented.
  219.  
  220. SEE ALSO
  221.     FreeNet(), SetDefault()
  222.  
  223. dignet.library/CallModemDP                         dignet.library/CallModemDP
  224. dignet.library/CallModemDT                         dignet.library/CallModemDT
  225.  
  226. NAME
  227.     CallModem -- Do the dialup and check procedure for you when dealing with
  228.                  modems (version 3).
  229.  
  230. SYNOPSIS
  231.  
  232.     baud=CallModemDP(net,number,buffer)
  233.                      a0  a1     a2
  234.  
  235.     ULONG CallModemDP(APTR, STRPTR, APTR);
  236.  
  237.  
  238.  
  239.     baud=CallModemDT(net,number,buffer)
  240.                      a0  a1     a2
  241.  
  242.     ULONG CallModemDT(APTR, STRPTR, APTR);
  243.  
  244.  
  245. FUNCTION
  246.     These functions will do the whole procedure for you to dial up a number,
  247.     check the result and return the connect rate. If successful CONNECT the
  248.     functions return the baudrate. If NULL is returned you should check your
  249.     buffer. It will contain what the modem returned such as "NO CARRIER",
  250.     "NO ANSWER", "BUSY", "NO DIALTONE", "ERROR", VOICE", "DELAYED" etc.
  251.     "CONNECT ..." is the only valid return string for these functions to make
  252.     them return true. The baudrate is extracted from the connect string.
  253.     Internally they use the ParseConnect() to get the baud rate, but they
  254.     copy the string first since ParseConnect() makes the buffer invalid.
  255.     Your buffer is due to the internal copy valid after this call and you can
  256.     use the ParseConnect() on it if you need to.
  257.  
  258.     If you want to use touch tone dial you can use CallModemDT(). If you of
  259.     some reason need pulse dial, call the CallModemDP(). The functions are
  260.     compatible and you should let the user of your program deside which one
  261.     to use. CallModemDT() is the most common function to call.
  262.  
  263.     The functions has 30 second timeout limit. If no answer to the dialup is
  264.     received within 30 seconds or something locks up, the functions will
  265.     return with error.
  266.  
  267.     Currently there is no way to terminate a dialup in progress from the
  268.     library. You can however call the HangupModem() anytime to break the dial
  269.     or to hangup a connection.
  270.  
  271. INPUTS
  272.     net    - ptr. to a valid net structure
  273.     number - null terminated string that contains the number to dial,
  274.              f.ex. "12345678"[0]
  275.     buffer - ptr. to a buffer to contain the result. Must be minimum 16
  276.              bytes.
  277.  
  278. RESULTS 
  279.     baud - the baudrate at connect or NULL if any error. Check your buffer if
  280.            NULL is returned.
  281.  
  282. AREXX
  283.     CallModemDT '"'<net>'"' <phonenumber>
  284.     CallModemDP '"'<net>'"' <phonenumber>
  285.  
  286.     These functions do not work properly from arexx yet.
  287.  
  288. NOTES
  289.     
  290. EXAMPLE
  291.     move.l    Net(pc),a0
  292.     lea    Number(pc),a1
  293.     lea    Buffer(pc),a2
  294.     Call    CallModemDT
  295.  
  296.     move.l    d0,Baud
  297.     beq    .error
  298. [...]
  299.  
  300. Number    dc.b    "12345678",0
  301. Buffer    dcb.b    16,0
  302.  
  303. BUGS
  304.     You should have a possibility to terminate a dialup in progress before
  305.     the phone in the other end picks up the line. You can with having a
  306.     subtask sending a HangupModem(), but this isn't reliable timewise.
  307.  
  308. SEE ALSO
  309.     HangupModem(), ParseConnect()
  310.  
  311. dignet.library/CaptureTextEnd                   dignet.library/CaptureTextEnd
  312.  
  313. NAME
  314.     CaptureTextEnd -- Stop capture to a file (version 4)
  315.  
  316. SYNOPSIS
  317.  
  318.     status=CaptureTextEnd(net)
  319.                         a0
  320.  
  321.     BOOL CaptureTextEnd(APTR);
  322.  
  323.  
  324. FUNCTION
  325.     To end a capture you must call this function. Resource tracking will end
  326.     the capture if you call FreeNet() as well. If there is no capture in
  327.     progress you will get returned FALSE, otherwise TRUE.
  328.  
  329.     You must also call this function if you want to start capturing to
  330.     another file as you can only capture to one file at the time.
  331.  
  332. INPUTS
  333.     net - ptr. to a valid net
  334.  
  335. RESULTS 
  336.     status - TRUE if file got closed, FALSE if no capture was enabled.
  337.  
  338. AREXX
  339.     CAPTURETEXTEND '"'net'"'
  340.  
  341. SEE ALSO
  342.     CaptureTextStart()
  343.  
  344. dignet.library/CaptureTextStart               dignet.library/CaptureTextStart
  345.  
  346. NAME
  347.     CaptureTextStart -- Start capture of bytes sent or received (version 4)
  348.  
  349. SYNOPSIS
  350.  
  351.     status=CaptureTextStart(net,filename,mode)
  352.                             a0  a1       d0
  353.  
  354.     BOOL CaptureTextStart(APTR,STRPTR,UWORD);
  355.  
  356.  
  357. FUNCTION
  358.     With this function you can capture bytes sent or received on the serial
  359.     port. The function will open a new file or append to an already existing
  360.     file. All data transfered or received on the net is saved to this file as
  361.     well. The function will return TRUE if file is ok, otherwise you will get
  362.     false. If you are already capturing you will get returned FALSE. The file
  363.     is closed (or capture stopped) by calling the function CaptureTextEnd().
  364.     The resource tracking will end the file for you when calling FreeNet(),
  365.     but please do program properly.
  366.  
  367.     You can either append a file using DNCAPTUREAPPEND as mode or create a
  368.     new file by using DNCAPTURENEW.
  369.  
  370.     Binaries (raw) chars will be captured too.
  371.  
  372. INPUTS
  373.     net - ptr. to a valid net
  374.     filename - ptr. to a null terminated string containing path and filename
  375.     mode - DNCAPTUREAPPEND or DNCAPTURENEW
  376.  
  377. RESULTS 
  378.     status - true if file is ok and you don't capture already, false if file
  379.              couldn't be created (due to error in path etc.) or if you are
  380.              already capturing to a file.
  381.  
  382. NOTES
  383.     Some functions may "swallow" their bytes sent or received (such as
  384.     InitModem() for instance). Support for these functions may be implemented
  385.     in future.
  386.  
  387.     You can only capture to one file at the time per net.
  388.  
  389. AREXX
  390.     CAPTURETEXTSTART '"'Net'"' <mode> <filename>
  391.  
  392.     mode =  0 -> new file
  393.     mode = -1 -> append file
  394.  
  395. EXAMPLE
  396.     
  397. BUGS
  398.     
  399. SEE ALSO
  400.     CaptureTextEnd(), dignet/dignet.i|h
  401.  
  402. dignet.library/ConvertModemString           dignet.library/ConvertModemString
  403.  
  404. NAME
  405.     ConvertModemString -- convert a standard modem string to binary/ascii
  406.        (version 3)
  407.  
  408. SYNOPSIS
  409.  
  410.     newstring=ConvertModemString(string)
  411.                                  a0
  412.  
  413.     STRPTR ConvertModemString(STRPTR);
  414.  
  415.  
  416. FUNCTION
  417.     This function converts strings used for modem such as "ATZ\r" to its
  418.     binary meaning. "ATZ\r" would become "ATZ"(13) in this example.
  419.     The function uses the same string buffer as you gave because a convertion
  420.     will always make the string shorter than the original string. It also
  421.     nullterminates the new string. If you allocated the string you should use
  422.     the original length to deallocate the new string.
  423.  
  424.     Currently this function only supports these C-style string commands:
  425.  
  426.     \b - backspace
  427.     \e - escape
  428.     \f - form feed
  429.     \n - linefeed
  430.     \r - carriage return
  431.     \t - tabulator
  432.  
  433.     The string you provide can contain binary codes as well. It only converts
  434.     "\*"-sequences and stops only when it finds a null byte.
  435.  
  436. INPUTS
  437.     string - ptr. to a string you want to send the modem
  438.  
  439. RESULTS 
  440.     newstring - ptr. to the converted string (same address as the string you
  441.                 provided with the function). NOTE: If string is unchanged you
  442.                 should check the string ptr. you gave or the string content.
  443.                 It will exit if a0=null
  444.  
  445. AREXX
  446.     CONVERTMODEMSTRING <string>
  447.     RESULT=newstring
  448.  
  449. NOTES
  450.     
  451. EXAMPLE
  452.  
  453.     NewString=ConvertModemString("ATZ\r")
  454.  
  455.         NewString <- ATZ(13)(0)
  456.     
  457. BUGS
  458.     
  459. SEE ALSO
  460.     InitModem()
  461.  
  462.  
  463. dignet.library/ConverseText                       dignet.library/ConverseText
  464.  
  465. NAME
  466.     ConverseText -- Waits for a string to be received and then send a string
  467.                     (version 4)
  468.  
  469. SYNOPSIS
  470.  
  471.     error=ConverseText(net,waitstring,putstring)
  472.                        a0  a1         a2
  473.  
  474.     ULONG ConverseText(APTR, STRPTR, STRPTR);
  475.  
  476.  
  477. FUNCTION
  478.     If you have seen NComm's script language you will probably recognice this
  479.     function. It waits for a specific string (case-sensitive) and when it get
  480.     the string it sends a string. Very useful if you want to make dialup
  481.     scripts (eg. you get login: and then you can send your login name etc.).
  482.  
  483.     To break waiting you can call the StopWaiting() function.
  484.  
  485. INPUTS
  486.     net - ptr. to a valid net
  487.     waitstring - ptr. to a null terminated string to wait for
  488.     putstring - ptr. to a null terminated string to send
  489.  
  490. RESULTS 
  491.     error - null if ok, else IO error
  492.  
  493. NOTES
  494.     The 'waitstring' is case-sensitive.
  495.  
  496. EXAMPLE
  497.     
  498. BUGS
  499.     
  500. SEE ALSO
  501.     WaitText()
  502.  
  503. dignet.library/FlushNet                               dignet.library/FlushNet
  504.  
  505. NAME
  506.     FlushNet -- Flushes the net buffers. Useful with AbortNet() (version 3)
  507.  
  508. SYNOPSIS
  509.  
  510.     error=FlushNet(net)
  511.                    a0
  512.  
  513.     ULONG FlushNet(APTR);
  514.  
  515.  
  516. FUNCTION
  517.     This function flushes the IO buffers used by a net. It's useful after you
  518.     AbortNet() a net to clean up garbage retuned on the port buffers. From
  519.     version 3 the function als have a safty routine after a flush. It reads
  520.     the net for garabge and put it to a nil function of the library. That
  521.     should guarantee pretty much that when this function returns the buffer
  522.     is empty.
  523.  
  524. INPUTS
  525.     net - ptr. to a valid net structure
  526.  
  527. RESULTS 
  528.     error - NULL if ok, io_error otherwise
  529.  
  530. NOTES
  531.     
  532. EXAMPLE
  533.     
  534. BUGS
  535.     
  536. SEE ALSO
  537.     AbortNet()
  538.  
  539. dignet.library/FreeNet                                 dignet.library/FreeNet
  540.  
  541. NAME
  542.     FreeNet -- Frees and cleanup the structure allocated with AllocNet()
  543.  
  544. SYNOPSIS
  545.  
  546.     error=FreeNet(net)
  547.             a0
  548.  
  549.     LONG FreeNet(APTR);
  550.  
  551.  
  552. FUNCTION
  553.     This function will free the structure allocated with AllocNet(). It will
  554.     also flush, abort, wait and close the device and then free memory
  555.     allocated with AllocNet().
  556.  
  557.     From version 2.1 this function now returns an error code. Null if ok, -1
  558.     (DNETERROR_WRONGNET) if you tried to free a net structure that had wrong
  559.     pointer. The error result is for debug purposes. You use it optionally,
  560.     but you should test it before a public release.
  561.  
  562.     If you get this error you gave it the wrong net structure pointer or the
  563.     net was already freed once.
  564.  
  565.     This feature is a bi-effect of the resource capabillity of the library
  566.     implemented in version 2.1.
  567.  
  568. INPUTS
  569.     net - ptr. to a valid net structure
  570.  
  571. RESULT
  572.     error - null if ok, dneterror_wrongnet if wrong net structure was tried
  573.             to get freed.
  574.  
  575. EXAMPLE
  576.     error=FreeNet(net)
  577.  
  578. NOTES
  579.     From version 2.1 this function returns an error code.
  580.  
  581. BUGS
  582.     
  583. SEE ALSO
  584.     AllocNet()
  585.  
  586. dignet.library/GetBaudrate                         dignet.library/GetBaudrate
  587.  
  588. NAME
  589.     GetBaudrate -- Returns the current initialized baudrate (version 3)
  590.  
  591. SYNOPSIS
  592.  
  593.     baudrate=GetBaudrate(net)
  594.                          a0
  595.  
  596.     ULONG GetBaudrate(APTR);
  597.  
  598.  
  599. FUNCTION
  600.     This function returns the currently used baudrate from the device. This
  601.     is not neccesarly the same baud speed as the modem connect with. However
  602.     the baud speed should be as high as possible.
  603.  
  604. INPUTS
  605.     net - ptr. to a valid net structure
  606.  
  607. RESULTS 
  608.     baudrate - usigned long integer with the device baud rate or NULL if
  609.                error
  610.  
  611. NOTES
  612.     It does not reflect the connect speed if you use the net with a modem.
  613.     See the ParseConnect() to obtain connect speed.
  614.  
  615. EXAMPLE
  616.     
  617. BUGS
  618.     
  619. SEE ALSO
  620.     SetBaud(), SetDefault()
  621.  
  622.  
  623. dignet.library/GetBitwidth                         dignet.library/GetBitwidth
  624.  
  625. NAME
  626.     GetBitwidth -- returns the current device used's bitwidth (version 4)
  627.  
  628. SYNOPSIS
  629.  
  630.     bitwidth=GetBitwidth(net)
  631.                          a0
  632.  
  633.     ULONG GetBitwidth(APTR);
  634.  
  635.  
  636. FUNCTION
  637.     This function returns the bitwidth of the device used in net.
  638.  
  639. INPUTS
  640.     net - ptr. to a valid net
  641.  
  642. RESULTS 
  643.     bitwidth - integervalue representing the bitwidth of device
  644.  
  645. NOTES
  646.  
  647. EXAMPLE
  648.  
  649. BUGS
  650.  
  651. SEE ALSO
  652.     SetBitwidth()
  653.  
  654. dignet.library/GetCurrentDevice               dignet.library/GetCurrentDevice
  655.  
  656. NAME
  657.     GetCurrentDevice -- returns a pointer to device name currently used.
  658.        (version 3)
  659.  
  660. SYNOPSIS
  661.  
  662.     devicename=GetCurrentDevice(net)
  663.                                 a0
  664.  
  665.     STRPTR GetCurrentDevice(APTR);
  666.  
  667.  
  668. FUNCTION
  669.     This function will return a pointer to the name of the device currently
  670.     used by the net. You should NOT change the content of the string. You are
  671.     allowed to copy the string to your own buffer.
  672.  
  673.     The name is correct as long as the net is valid and the above rule is
  674.     followed.
  675.  
  676. INPUTS
  677.     net - ptr. to a valid net structure
  678.  
  679. RESULTS 
  680.     devicename - ptr. to a nullterminated string containing the device name
  681.                  of the device currently beeing used. NULL if error.
  682.  
  683. NOTES
  684.     
  685. EXAMPLE
  686.     
  687. BUGS
  688.     
  689. SEE ALSO
  690.     GetCurrentUnit()
  691.  
  692. dignet.library/GetCurrentUnit                   dignet.library/GetCurrentUnit
  693.  
  694. NAME
  695.     GetCurrentUnit -- Returns unit number of device used (version 3)
  696.  
  697. SYNOPSIS
  698.  
  699.     unit=GetCurrentUnit(net)
  700.                         a0
  701.  
  702.     UWORD GetCurrentUnit(APTR);
  703.  
  704.  
  705. FUNCTION
  706.     This function returns the unit number of the device currently beeing used
  707.     by the net structure. The number is always correct if the net is valid.
  708.  
  709. INPUTS
  710.     net - ptr. to a valid net structure
  711.  
  712. RESULTS 
  713.     unit - unit number or -1 if error
  714.  
  715. NOTES
  716.     
  717. EXAMPLE
  718.     
  719. BUGS
  720.     
  721. SEE ALSO
  722.     GetCurrentDevice()
  723.  
  724.  
  725. dignet.library/GetHandshake                       dignet.library/GetHandshake
  726.  
  727. NAME
  728.     GetHandshake -- Get current handshake mode of net device (version 4)
  729.  
  730. SYNOPSIS
  731.  
  732.     mode=GetHandshake(net)
  733.                       a0
  734.  
  735.     ULONG GetHandshake(APTR);
  736.  
  737.  
  738. FUNCTION
  739.     This function will return the current handshake mode of the device used
  740.     in the net. See the include file for modes.
  741.  
  742.     NOT ACTIVATED IN 4.0 - You may use it for future compability (will return
  743.     null in 4.0)
  744.  
  745. INPUTS
  746.     net - ptr. to a valid net
  747.  
  748. RESULTS 
  749.     mode - see include file for handshake modes
  750.  
  751. NOTES
  752.     
  753. EXAMPLE
  754.     
  755. BUGS
  756.     NOT ACTIVATED IN 4.0
  757.  
  758. SEE ALSO
  759.     Sethandshake()
  760.  
  761. dignet.library/GetIOmsg                               dignet.library/GetIOmsg
  762.  
  763. NAME
  764.     GetIOmsg -- Returns a pointer to the IO msg used (version 3)
  765.  
  766. SYNOPSIS
  767.  
  768.     iomsg=GetIOmsg(net)
  769.                    a0
  770.  
  771.     struct iomsg * GetIOmsg(APTR);
  772.  
  773.  
  774. FUNCTION
  775.     This function returns a pointer to a IOMSG structure used by the device.
  776.     Useful if user want to use the device in a more advanced way.
  777.  
  778. INPUTS
  779.     net - ptr. to a valid net structure
  780.  
  781. RESULTS 
  782.     iomsg - ptr. to a iomsg structure or NULL if error
  783.  
  784. NOTES
  785.     
  786. EXAMPLE
  787.     
  788. BUGS
  789.     
  790. SEE ALSO
  791.     GetNetport()
  792.  
  793. dignet.library/GetModemStatus                   dignet.library/GetModemStatus
  794.  
  795. NAME
  796.     GetModemStatus -- Returns a bool of the assumed modem state (version 3)
  797.  
  798. SYNOPSIS
  799.  
  800.     status=GetModemStatus(net)
  801.                           a0
  802.  
  803.     BOOL GetModemStatus(APTR);
  804.  
  805.  
  806. FUNCTION
  807.     This function returns a bool of what it thinks the current modem state
  808.     is. If false the modem is assumed offline, if true the modem is assumed
  809.     to be online. The reason why it has to assume the status if because after
  810.     a successful modem dial the user can turn off the modem and on again. The
  811.     net structure doesn't know about this.
  812.  
  813. INPUTS
  814.     net - ptr. to a valid net structure
  815.  
  816. RESULTS 
  817.     status - BOOL, true if modem is assumed online, false if assumed offline
  818.              You will get FALSE if error.
  819.  
  820. NOTES
  821.     The function only assumes the status, it doesn't know for sure.
  822.  
  823. EXAMPLE
  824.     
  825. BUGS
  826.     Should find a way to check the real status. Some active line or
  827.     something. If some of you know, please report to kenny@bgnett.no
  828.  
  829. SEE ALSO
  830.     CallModem(), HangupModem()
  831.  
  832. dignet.library/GetNetport                           dignet.library/GetNetport
  833.  
  834. NAME
  835.     GetNetport -- Returns the pointer to the msg port used for net (ver 2)
  836.  
  837. SYNOPSIS
  838.  
  839.     port=GetNetport(net)
  840.                     a0
  841.  
  842.     struct MP* GetNetport(APTR);
  843.  
  844.  
  845. FUNCTION
  846.     This function return a pointer to the public message port used by this
  847.     library. You are free to name it. You can with this function use this
  848.     more advanced uses such as collecting port signals and Wait() them.
  849.  
  850.     No need to use this function if you don't require advanced uses.
  851.  
  852. INPUTS
  853.     net - ptr. to a valid net structure
  854.  
  855. RESULTS 
  856.     port - ptr. to a message port (public). NULL if error.
  857.  
  858. NOTES
  859.     After a FreeNet() call the port is invalid!
  860.  
  861. EXAMPLE
  862.     
  863. BUGS
  864.     
  865. SEE ALSO
  866.     GetIOmsg()
  867.  
  868. dignet.library/GetParity                             dignet.library/GetParity
  869.  
  870. NAME
  871.     GetParity -- Get current parity mode used in device/net (version 4)
  872.  
  873. SYNOPSIS
  874.  
  875.     mode=GetParity(net)
  876.                    a0
  877.  
  878.     ULONG GetParity(APTR);
  879.  
  880.  
  881. FUNCTION
  882.     This function will return the current parity mode used by the device in
  883.     the net structure. See include file for parity mode.
  884.  
  885.     NOT ACTIVATED IN 4.0 - You may use it for future compability (will return
  886.     null in 4.0)
  887.  
  888. INPUTS
  889.     net - ptr. to a valid net
  890.  
  891. RESULTS 
  892.     mode - parity mode used (see include file)
  893.  
  894. NOTES
  895.     
  896. EXAMPLE
  897.     
  898. BUGS
  899.     NOT ACTIVE IN 4.0
  900.  
  901. SEE ALSO
  902.     SetParity()
  903.  
  904. dignet.library/GetStopbits                         dignet.library/GetStopbits
  905.  
  906. NAME
  907.     GetStopbits -- returns the number of stopbits used in device (version 4)
  908.  
  909. SYNOPSIS
  910.  
  911.     stopbits=GetStopbits(net)
  912.                          a0
  913.  
  914.     ULONG GetStopbits(APTR);
  915.  
  916.  
  917. FUNCTION
  918.     This function will return number of stopbits used by device. Usually it
  919.     will be 1.
  920.  
  921. INPUTS
  922.     net - ptr. to a valid net
  923.  
  924. RESULTS 
  925.     stopbits - number of stopbits
  926.  
  927. NOTES
  928.     
  929. EXAMPLE
  930.     
  931. BUGS
  932.     
  933. SEE ALSO
  934.     SetStopbits()
  935.  
  936. dignet.library/HangupModem                         dignet.library/HangupModem
  937.  
  938. NAME
  939.     HangupModem -- send break and hangup command to modem (version 3)
  940.  
  941. SYNOPSIS
  942.  
  943.     error=HangupModem(net)
  944.                       a0
  945.  
  946.     ULONG HangupModem(APTR);
  947.  
  948.  
  949. FUNCTION
  950.     This function send the a break and hangup command to the modem. The
  951.     string it sends is "\w\w+++\w\w\w\wATH\r". This is a standard way to
  952.     hangup the modem when online. If you need to hangup the modem otherwise
  953.     you should use the WriteNet() function to write your string to the modem
  954.     that hang it up. The function will use 3.5 seconds on the hangup.
  955.     It also sends the ATH command twice.
  956.  
  957.     You could take a FlushNet() after a HangupModem() call.
  958.  
  959. INPUTS
  960.     net - ptr. to a valid net structure
  961.  
  962. RESULTS 
  963.     error - NULL if OK when sending, io_error otherwise
  964.  
  965. NOTES
  966.     Sending a break and hangup command to the modem does NOT guarantee the
  967.     modem to hang up. You should check the lights on your modem if it really
  968.     hung up.
  969.  
  970. EXAMPLE
  971.     
  972. BUGS
  973.     
  974. SEE ALSO
  975.     WriteNet()
  976.  
  977. dignet.library/InitIOEXT                             dignet.library/InitIOEXT
  978.  
  979. NAME
  980.     InitIOEXT -- Init the IOEXT structure of a device (serial/duart etc.)
  981.  
  982. SYNOPSIS
  983.  
  984.     error=InitIOEXT(net,newIOEXT,size)
  985.                     a0  a1       d0
  986.  
  987.     ULONG InitIOEXT(APTR, APTR *, ULONG);
  988.  
  989.  
  990. FUNCTION
  991.     This function will init the IOEXT and call the device function
  992.     SetParameters. Only use this with devices that are compatible with the
  993.     serial device (for example duart.device).
  994.  
  995.     Always use the ReadIOEXT() first to copy current settings of the device
  996.     to your buffer. This way you only have to change some fields. If not you
  997.     will have to setup the whole IOEXT struture.
  998.  
  999. INPUTS
  1000.     net - ptr. to a valid net structure
  1001.     newIOEXT - ptr. to new settings (IOEXTSER structure)
  1002.     size - number of bytes to copy
  1003.  
  1004. RESULTS 
  1005.     error - reflects the io_error field. Null if ok.
  1006.  
  1007. NOTES
  1008.     For C users: Use struct IOEXTSER *, but you need to add $30 to the
  1009.     structure's beginning since this function copy only the IOEXTSER part!
  1010.  
  1011.     Currently max number of chars to read should be 80 bytes.
  1012.     
  1013. EXAMPLE
  1014.  
  1015. BUGS
  1016.     Should perhaps used the whole IO stucture to make it more simpler for C
  1017.     users.
  1018.  
  1019. SEE ALSO
  1020.     ReadIOEXT(), devices/serial.i|h, dignet/dignet.i|h
  1021.  
  1022.  
  1023. dignet.library/InitModem                             dignet.library/InitModem
  1024.  
  1025. NAME
  1026.     InitModem -- Inits a modem with a standard initstring (version 3)
  1027.  
  1028. SYNOPSIS
  1029.  
  1030.     error=InitModem(net,initstring,buffer)
  1031.                     a0  a1         a2
  1032.  
  1033.     ULONG InitModem(APTR,STRPTR,APTR);
  1034.  
  1035.  
  1036. FUNCTION
  1037.     The function converts the string and sends it to the net where it expect
  1038.     a modem to be. If no modem found it return with either timeout error or
  1039.     error code from the io_error field.
  1040.  
  1041.     A string could be: "ATZ\r"[0] and the function converts this to:
  1042.  
  1043.         ATZ(13) [13=Carriage Return/CR]
  1044.  
  1045.     Currently this function only supports these C-style string commands:
  1046.  
  1047.     \b - backspace
  1048.     \e - escape
  1049.     \f - form feed
  1050.     \n - linefeed
  1051.     \r - carriage return
  1052.     \t - tabulator
  1053.  
  1054.     Other commands will be ignored.
  1055.  
  1056.     The function copies the io_actual error code to result and the string the
  1057.     modem replies with to the buffer you provided so you can check or print
  1058.     the result (eg. OK or ERROR). Note that the buffer must be atleast 16
  1059.     bytes long.
  1060.  
  1061.     If user provides a init string which dumps much data, this function will
  1062.     crop that stream to 16 bytes so it'll fit into the buffer. With correct
  1063.     use of the init string the modem should return 3 bytes OK(13).
  1064.  
  1065. INPUTS
  1066.     net - ptr. to a valid net structure
  1067.     initstring - ptr. to a nullterminated init string (required from 3.03).
  1068.     buffer - ptr. to buffer. Minimum 16 bytes long. Contains modem result.
  1069.  
  1070. RESULTS 
  1071.     error - NULL if ok, DNETERROR_TIMEOUT if timeout (maybe no modem),
  1072.             or io_error in all other cases. You should check the buffer
  1073.             in any case.
  1074.  
  1075. NOTES
  1076.     From 3.03 you MUST supply an Initstring in A1 !
  1077.  
  1078.     The buffer you provide must be a minimum of 16 bytes long (it will never
  1079.     read more than 16 bytes into the buffer).
  1080.  
  1081.     This routine gives the modem 3 seconds to reply. It returns immediatly if
  1082.     it receives a reply from the modem.
  1083.  
  1084. EXAMPLE
  1085.     To check the buffer if it is empty or not you could do (from assembler):
  1086.  
  1087.     lea    Buffer,a0
  1088.     tst.b    (a0)
  1089.     beq    .empty
  1090.  
  1091. BUGS
  1092.     Kept only a copy of the echo from modem (the init string itself). Now it
  1093.     will strip the echo till there has been two CR's and then it copies the
  1094.     rest into the buffer. Note that due to this the function may fail (return
  1095.     not-null), but this works fine with USRobotics modems. Please report to
  1096.     our email address if you can't get this function to work with your modem.
  1097.  
  1098. SEE ALSO
  1099.     CallModem(), ConvertModemString()
  1100.  
  1101. dignet.library/ObtainNet                             dignet.library/ObtainNet
  1102.  
  1103. NAME
  1104.     ObtainNet -- to share a net from another task (version 3)
  1105.  
  1106. SYNOPSIS
  1107.  
  1108.     net=ObtainNet(taskname)
  1109.                   a0
  1110.  
  1111.     APTR ObtainNet(STRPTR);
  1112.  
  1113.  
  1114. FUNCTION
  1115.     This function will try to find a net allocated by taskname. If success
  1116.     this function will return with a pointer to the netstructure.
  1117.  
  1118.     NOTE: It's never safe to use the net structure since you don't know if
  1119.     the net owner task frees it. You should have very special reasons to use
  1120.     this function, probably debug reasons or sub tasks that want to use the
  1121.     net. If so control the freeing with flags or similar.
  1122.  
  1123.     There will maybe be locking functions in future.
  1124.  
  1125. INPUTS
  1126.     taskname - ptr. to a taskname
  1127.  
  1128. RESULTS 
  1129.     net - net structure if success or NULL
  1130.  
  1131. NOTES
  1132.     Use this for special reasons only!
  1133.     
  1134. EXAMPLE
  1135.     
  1136. BUGS
  1137.     
  1138. SEE ALSO
  1139.     AllocNet()
  1140.  
  1141. dignet.library/ParseConnect                       dignet.library/ParseConnect
  1142.  
  1143. NAME
  1144.     ParseConnect -- Converts a connect string to baudrate (version 3)
  1145.  
  1146. SYNOPSIS
  1147.  
  1148.     baudrate=ParseConnect(buffer)
  1149.                           a0
  1150.  
  1151.     ULONG ParseConnect(APTR);
  1152.  
  1153.  
  1154. FUNCTION
  1155.     This function will try to convert a CONNECT string returned by
  1156.     CallModem() in buffer. It then returns the integer value of the connect
  1157.     speed (real speed).
  1158.  
  1159.     If buffer contains error messages or is empty this function will return
  1160.     NULL. The buffer is considered invalid after you have used this function
  1161.     on it!
  1162.  
  1163. INPUTS
  1164.     buffer - ptr. to the buffer CallModem() returned its connect string.
  1165.  
  1166. RESULTS 
  1167.     baudrate - unsigned long integer containing baudrate or NULL if invalid
  1168.                buffer
  1169.  
  1170. NOTES
  1171.     The buffer is considered invalid after you have used this function on it!
  1172.     
  1173. EXAMPLE
  1174.     
  1175. BUGS
  1176.     
  1177. SEE ALSO
  1178.     CallModemDT(), CallModemDP()
  1179.  
  1180. dignet.library/QueryNet                               dignet.library/QueryNet
  1181.  
  1182. NAME
  1183.     QueryNet -- Query the device and return number of chars that are
  1184.                 available for read.
  1185.  
  1186. SYNOPSIS
  1187.  
  1188.     chars=QueryNet(net)
  1189.                    a0
  1190.  
  1191.     ULONG QueryNet(APTR);
  1192.  
  1193.  
  1194. FUNCTION
  1195.     Use this function before you ReadNet() the device. This function will
  1196.     return number of bytes that are available to read. You can parse the
  1197.     result directly to ReadNet(). If zero bytes the ReadNet() will abort and
  1198.     return immediatly.
  1199.  
  1200. INPUTS
  1201.     net - ptr. to a valid net structure
  1202.  
  1203. RESULTS 
  1204.     chars - number of chars available to read
  1205.  
  1206. NOTES
  1207.     
  1208. EXAMPLE
  1209.     
  1210. BUGS
  1211.     
  1212. SEE ALSO
  1213.     ReadNet()
  1214.  
  1215. dignet.library/ReadIOEXT                             dignet.library/ReadIOEXT
  1216.  
  1217. NAME
  1218.     ReadIOEXT -- Copies current settings in IOEXT to a buffer
  1219.  
  1220. SYNOPSIS
  1221.  
  1222.     ReadIOEXT(net,buffer,size)
  1223.                a0  a1     d0
  1224.  
  1225.     void ReadIOEXT(APTR,APTR,ULONG);
  1226.  
  1227.  
  1228. FUNCTION
  1229.     This function will copy current setting of the IOEXT structure used to
  1230.     for example to set baud rate in the serial device. The device has to be
  1231.     compatible with the serial device to read successfully. The reason for
  1232.     this is that it reads from an offset that is valid for the serial.device.
  1233.     If another device has its IOEXT structure at same offset this function
  1234.     and the InitIOEXT() function can be used. Remember to set number of
  1235.     bytes to copy.
  1236.  
  1237. INPUTS
  1238.     net - ptr. to a valid net structure
  1239.     buffer - ptr. to a buffer to copy to
  1240.     size - number of bytes to copy
  1241.  
  1242. NOTES
  1243.     Currently max number of chars to read should be 80 bytes.
  1244.  
  1245.     DO NOT use devices that are not compatible with the serial.device or
  1246.     the IOEXTSER structure!
  1247.  
  1248. EXAMPLE
  1249.     
  1250. BUGS
  1251.     
  1252. SEE ALSO
  1253.     InitIOEXT(), devices/serial.i|h, dignet/dignet.i|h
  1254.  
  1255. dignet.library/ReadNet                                 dignet.library/ReadNet
  1256.  
  1257. NAME
  1258.     ReadNet -- reads x bytes from the device
  1259.  
  1260. SYNOPSIS
  1261.  
  1262.     error=ReadNet(net,buffer,size)
  1263.                   a0  a1     d0
  1264.  
  1265.     ULONG ReadNet(APTR,APTR,ULONG);
  1266.  
  1267.  
  1268. FUNCTION
  1269.     This function will read from the device. You should first call a query
  1270.     function to check the number of bytes waiting and then read those into
  1271.     your buffer. If zero bytes this function will abort immediatly so it is
  1272.     safe to call it. If you ask for more bytes than are available this
  1273.     function will wait until the amount can be read from the port. Use
  1274.     AbortNet() to cancel the wait or use Timeout() to give some time to get
  1275.     some bytes on the port before a ReadNet() is called. This function reads
  1276.     byte-by-byte to not miss any chars from the buffer.
  1277.  
  1278. INPUTS
  1279.     net - ptr. to a valid net structure
  1280.     buffer - ptr. to a buffer
  1281.     size - number of bytes to read
  1282.  
  1283. RESULTS 
  1284.     error - null if ok, else it reflects the io_error field
  1285.  
  1286. NOTES
  1287.     
  1288. EXAMPLE
  1289.     error=ReadNet(net,buffer,queryresult|timeoutresult)
  1290.  
  1291. BUGS
  1292.     
  1293. SEE ALSO
  1294.     WriteNet(), QueryNet(), AbortNet(), Timeout()
  1295.  
  1296. dignet.library/ReadString                           dignet.library/ReadString
  1297.  
  1298. NAME
  1299.     ReadString -- read a null terminated string from net (version 2)
  1300.  
  1301. SYNOPSIS
  1302.  
  1303.     error=ReadString(net,buffer,max)
  1304.                      a0  a1     d0
  1305.  
  1306.     ULONG ReadString(APTR,APTR,ULONG);
  1307.  
  1308.  
  1309. FUNCTION
  1310.     This function will read a string until it reaches a null termination byte
  1311.     or buffer overflows. Useful with the function WriteString() which sends a
  1312.     null terminated string to the net.
  1313.  
  1314.     CHANGES: if this function returns -1 (from version 2.1) it means buffer
  1315.     overflow. You should act on that and continue to read after you have
  1316.     cleaned up. Other non-null returns are errors returned from io_error
  1317.     field. Consult the serial.device documentation to get the definitions on
  1318.     those.
  1319.  
  1320. INPUTS
  1321.     net - ptr. to a valid net structure
  1322.     buffer - ptr. to buffer to keep the string
  1323.     max - max length of string
  1324.  
  1325. RESULTS 
  1326.     error - NULL if OK. -1 if buffer overflow, otherwise io_error.
  1327.  
  1328. NOTES
  1329.     NOTE WELL: This function returns -1 from version 2.1. It returned 1 in
  1330.     earlier version, but that could conflict with the dev_busy error (1).
  1331.     Please update your programs. Sorry for the inconvinient.
  1332.  
  1333. EXAMPLE
  1334.     
  1335. BUGS
  1336.     See notes!
  1337.  
  1338. SEE ALSO
  1339.     WriteString(), QueryNet(), Timeout(), AbortNet()
  1340.  
  1341. dignet.library/SetBaud                                 dignet.library/SetBaud
  1342.  
  1343. NAME
  1344.     SetBaud -- updeates the device with a new baudrate (version 3).
  1345.  
  1346. SYNOPSIS
  1347.  
  1348.     error=SetBaud(net,baud)
  1349.                   a0  d0
  1350.  
  1351.     ULONG SetBaud(APTR,ULONG);
  1352.  
  1353.  
  1354. FUNCTION
  1355.     Use this function to update just the baud rate. The baudrate should be an
  1356.     integer value, for example: baud=38400.
  1357.  
  1358. INPUTS
  1359.     net - ptr. to a valid net structure
  1360.     baud - integer value describing the baud rate.
  1361.  
  1362. RESULTS 
  1363.     error - NULL if OK, otherwise io_error or -1 if a0 or d0 is null.
  1364.  
  1365. NOTES
  1366.     Most devices communciating with the serial port do not support baud rates
  1367.     in a linear way. Read the documentation about which baud rates the device
  1368.     supports.
  1369.  
  1370. EXAMPLE
  1371.     
  1372. BUGS
  1373.     
  1374. SEE ALSO
  1375.     ReadIOExt(), InitIOExt()
  1376.  
  1377.  
  1378. dignet.library/SetBitwidth                         dignet.library/SetBitwidth
  1379.  
  1380. NAME
  1381.     SetBitwidth -- Set bitwidth of transfer bytes of device (version 4)
  1382.  
  1383. SYNOPSIS
  1384.  
  1385.     error=SetBitwidth(net,width)
  1386.                       a0  d0
  1387.  
  1388.     BOOL SetBitwidth(APTR,UBYTE);
  1389.  
  1390.  
  1391. FUNCTION
  1392.     This function will set new bitwidth in IOEXT on each char transfered.
  1393.     Then it calls SetParameter with DoIO().
  1394.  
  1395. INPUTS
  1396.     net - ptr. to a valid net
  1397.     width - char width (usually 8, in some cases 7)
  1398.  
  1399. RESULTS 
  1400.     error - true if ok, otherwise false (0)
  1401.  
  1402. NOTES
  1403.     
  1404. EXAMPLE
  1405.     
  1406. BUGS
  1407.     Still at beta state
  1408.  
  1409. SEE ALSO
  1410.     GetBitwidth()
  1411.  
  1412. dignet.library/SetDefault                           dignet.library/SetDefault
  1413.  
  1414. NAME
  1415.     SetDefault -- Set default parameters to a "safe" setup (version 3)
  1416.  
  1417. SYNOPSIS
  1418.  
  1419.     error=SetDefault(net)
  1420.                      a0
  1421.  
  1422.     ULONG SetDefault(APTR);
  1423.  
  1424.  
  1425. FUNCTION
  1426.     This function will initialize the modem with considered "safe" settings.
  1427.     the following parameters are set:
  1428.  
  1429.     Buffer size: 8194
  1430.     Flags: 7WIRE + BOGGIE + XDISABLED + NOPARITY (RTS/CTS handshaking)
  1431.     BAUD: 38400 (this is not the connect baud)
  1432.           8 bits per char
  1433.           1 stopbit
  1434.  
  1435.     This setup should work for any Amiga. If you have a slow Amiga (68000 or
  1436.     68010) you should use the SetBaud() function and set baud to 19200. If
  1437.     you have a faster Amiga than 68030/25 Mhz you can set use the SetBaud()
  1438.     function to set 57000 or better. The BOGGIE and 7WIRE make sure that you
  1439.     can accept highspeed transfers. Without those you may get garbage. You
  1440.     can use the ReadIOEXT() and InitIOEXT() to change flags and more.
  1441.  
  1442. INPUTS
  1443.     net - ptr. to a valid net structure
  1444.  
  1445. RESULTS 
  1446.     error - NULL if ok, otherwise io_error
  1447.  
  1448. NOTES
  1449.     
  1450. EXAMPLE
  1451.     
  1452. BUGS
  1453.     The serflags was put into extflags instead. Now fixed!
  1454.  
  1455. SEE ALSO
  1456.     SetBaud(), ReadIOEXT(), InitIOEXT()
  1457.  
  1458.  
  1459.  
  1460. dignet.library/SetHandshake                       dignet.library/SetHandshake
  1461.  
  1462. NAME
  1463.     SetHandshake -- Set new handshake protocol on device (version 4)
  1464.  
  1465. SYNOPSIS
  1466.  
  1467.     error=SetHandshake(net,handshake)
  1468.                        a0  d0
  1469.  
  1470.     BOOL SetHandshake(APTR,UWORD);
  1471.  
  1472.  
  1473. FUNCTION
  1474.     To change the device's protocol handshaking use this function for
  1475.     convinient. The function sets the approriate flags in the IOEXT structure
  1476.     and calls SetParameters with DoIO.
  1477.  
  1478. INPUTS
  1479.     net - ptr. to a valid net
  1480.     handshake - handshake type (see include)
  1481.  
  1482. RESULTS 
  1483.     error - true if success otherwise false (0).
  1484.  
  1485. NOTES
  1486.     
  1487. EXAMPLE
  1488.     
  1489. BUGS
  1490.     Still at beta state
  1491.  
  1492. SEE ALSO
  1493.     GetHandshake()
  1494.  
  1495. dignet.library/SetParity                             dignet.library/SetParity
  1496.  
  1497. NAME
  1498.     SetParity -- Set new parity to net (version 4)
  1499.  
  1500. SYNOPSIS
  1501.  
  1502.     error=SetParity(net,paritymode)
  1503.                     a0  d0
  1504.  
  1505.     BOOL SetParity(APTR, UWORD);
  1506.  
  1507.  
  1508. FUNCTION
  1509.     With this function you can easily set new parity to the current net. You
  1510.     must use one of the parity modes (see dignet.i|h for modes). The new
  1511.     parity is triggered immediatly.
  1512.  
  1513. INPUTS
  1514.     net - ptr. to a valid net
  1515.     paritymode - (see dignet.i for the different modes).
  1516.  
  1517. RESULTS 
  1518.     error - TRUE is OK, FALSE if mode is unknown or it couldn't set this
  1519.             parity mode to this net.
  1520.  
  1521. NOTES
  1522.  
  1523. EXAMPLE
  1524.  
  1525. BUGS
  1526.  
  1527. SEE ALSO
  1528.     GetParity()
  1529.  
  1530.  
  1531. dignet.library/SetStopbits                         dignet.library/SetStopbits
  1532.  
  1533. NAME
  1534.     SetStopbits -- Sets number of stop bits in IOEXT (version 4)
  1535.  
  1536. SYNOPSIS
  1537.  
  1538.     error=SetStopbits(net,bits)
  1539.                       a0  d0
  1540.  
  1541.     BOOL SetStopbits(APTR,UBYTE);
  1542.  
  1543.  
  1544. FUNCTION
  1545.     This function will set number of stop bits and call SetParameters with
  1546.     DoIO() for you.
  1547.  
  1548. INPUTS
  1549.     net - ptr. to a valid net
  1550.     bits - number of stop bits (usually 1, in some cases 2)
  1551.  
  1552. RESULTS 
  1553.     error - true if ok, otherwise false
  1554.  
  1555. NOTES
  1556.     
  1557. EXAMPLE
  1558.     
  1559. BUGS
  1560.     Still at beta state
  1561.  
  1562. SEE ALSO
  1563.     GetStopbits()
  1564.  
  1565. dignet.library/StopWaiting                         dignet.library/StopWaiting
  1566.  
  1567. NAME
  1568.     StopWaiting -- Terminates a WaitModem() call (version 3)
  1569.  
  1570. SYNOPSIS
  1571.  
  1572.     StopWaiting(net)
  1573.                 a0
  1574.  
  1575.     void StopWaiting(APTR);
  1576.  
  1577.  
  1578. FUNCTION
  1579.     This function sends a terminate message to the WaitModem() function. The
  1580.     WaitModem() will otherwise never return if it not receive a RING string
  1581.     first. It may take some seconds before the function returns after the
  1582.     terminate message is sent. The buffer should contain "TERMINATED" if this
  1583.     was the reason.
  1584.  
  1585.     From version 4 this function will also break WaitText() and
  1586.     ConverseText().
  1587.  
  1588. INPUTS
  1589.     net - ptr. to a valid net structure
  1590.  
  1591. NOTES
  1592.     Calling it with no WaitModem() waiting has no effect and is safe.
  1593.  
  1594. EXAMPLE
  1595.     
  1596. BUGS
  1597.     
  1598. SEE ALSO
  1599.     WaitModem()
  1600.  
  1601. dignet.library/Timeout                                 dignet.library/Timeout
  1602.  
  1603. NAME
  1604.     Timeout -- waits x seconds to receive char(s) on the device for reading
  1605.  
  1606. SYNOPSIS
  1607.  
  1608.     chars=Timeout(net,seconds)
  1609.                   a0  d0
  1610.  
  1611.     ULONG Timeout(APTR,UWORD);
  1612.  
  1613.  
  1614. FUNCTION
  1615.     You can use this function to give a device a certain amont of time to get
  1616.     a char or more on the port for reading. You set seconds to wait. If a
  1617.     char or more is received the function will return with the current amount
  1618.     of chars in buffer. If timeout occure it will return with NULL.
  1619.  
  1620.     Null seconds is valid, however it will just call the QueryNet() function
  1621.     instead and return immediatly.
  1622.  
  1623.     If you lock up waiting for chars with ReadNet() or ReadString() use the
  1624.     AbortNet() function.
  1625.  
  1626. INPUTS
  1627.     net - ptr. to a valid net structure
  1628.     seconds - number of seconds to wait for timeout
  1629.  
  1630. RESULTS 
  1631.     chars - number of chars received before timeout or NULL if none
  1632.  
  1633. NOTES
  1634.     The seconds are divided in smaller parts so the function don't have to
  1635.     wait a whole second to return if there are chars on the buffer.
  1636.  
  1637. EXAMPLE
  1638.     
  1639. BUGS
  1640.     It should use WaitPort() instead of Delay() + Query. Will maybe be fixed
  1641.     in future.
  1642.  
  1643. SEE ALSO
  1644.     QueryNet(), AbortNet()
  1645.  
  1646.  
  1647. dignet.library/WaitModem                             dignet.library/WaitModem
  1648.  
  1649. NAME
  1650.     WaitModem -- Waits for a incoming modem call (3)
  1651.  
  1652. SYNOPSIS
  1653.  
  1654.     baud=WaitModem(net,buffer)
  1655.                    a0  a1
  1656.  
  1657.     ULONG WaitModem(APTR, APTR);
  1658.  
  1659.  
  1660. FUNCTION
  1661.     When you call this function the library goes into a wait mode on a modem
  1662.     call. The call is detected with a "RING" signal. If the modem can connect
  1663.     it returns the speed it connected with in a unsigned long word integer,
  1664.     else it will return null if it was any error such as a voice or fax call
  1665.     instead. The buffer contains a string the modem sends when connecting.
  1666.  
  1667.     To break the wait you need to call the StopWaiting() function on the net
  1668.     which is waiting. This is preferable done from a sub-task.
  1669.  
  1670. INPUTS
  1671.     net - ptr. to a valid net
  1672.     buffer - ptr. to a buffer (min 16 bytes)
  1673.  
  1674. RESULTS 
  1675.     baud - the actual connect speed if success or null if any errors
  1676.  
  1677. NOTES
  1678.     
  1679. EXAMPLE
  1680.     
  1681. BUGS
  1682.     
  1683. SEE ALSO
  1684.     StopWaiting()
  1685.  
  1686.  
  1687. dignet.library/WaitText                               dignet.library/WaitText
  1688.  
  1689. NAME
  1690.     WaitText -- Waits for a string to be read on the port (version 4)
  1691.  
  1692. SYNOPSIS
  1693.  
  1694.     error=WaitText(net,waitstring)
  1695.                     a0  a1
  1696.  
  1697.     ULONG WaitText(APTR,STRPTR);
  1698.  
  1699.  
  1700. FUNCTION
  1701.     This function will wait until it receives a string equal to waitstring on
  1702.     the port. To break the waiting use the StopWaiting() function.
  1703.  
  1704. INPUTS
  1705.     net - ptr. to a valid net
  1706.     waitstring - ptr. to a nullterminated string to wait for (may contain
  1707.                  binaries)
  1708.  
  1709. RESULTS 
  1710.     error - null if ok, else IO error
  1711.  
  1712. NOTES
  1713.     String is case-sensitive.
  1714.  
  1715. EXAMPLE
  1716.     
  1717. BUGS
  1718.     
  1719. SEE ALSO
  1720.     ConverseText()
  1721.  
  1722. dignet.library/WriteNet                               dignet.library/WriteNet
  1723.  
  1724. NAME
  1725.     WriteNet -- Writes x bytes to the device
  1726.  
  1727. SYNOPSIS
  1728.  
  1729.     error=WriteNet(net,buffer,size)
  1730.                    a0  a1     d0
  1731.  
  1732.     ULONG WriteNet(APTR,APTR,ULONG);
  1733.  
  1734.  
  1735. FUNCTION
  1736.     This function write a number of bytes (really a copy) from a buffer of
  1737.     size x. The function returns immediatly.
  1738.  
  1739. INPUTS
  1740.     net - ptr. to a valid net structure
  1741.     buffer - ptr. to a buffer taht contains bytes to write
  1742.     size - number of bytes to write
  1743.  
  1744. RESULTS 
  1745.     error - reflects the io_error field. Null if ok.
  1746.  
  1747. NOTES
  1748.     
  1749. EXAMPLE
  1750.     error=WriteNet(net,buffer,3351)
  1751.  
  1752. BUGS
  1753.     In earlier versions there had to be implemented a delay of 20/50 of a
  1754.     second to get all chars read from the io buffer. This is fixed for
  1755.     the version 2 release. The library now read and writes byte-by-byte to
  1756.     not loose any chars.
  1757.  
  1758. SEE ALSO
  1759.     ReadNet()
  1760.  
  1761. dignet.library/WriteString                         dignet.library/WriteString
  1762.  
  1763. NAME
  1764.     WriteString -- Writes a nullterminated string to net (v.2)
  1765.  
  1766. SYNOPSIS
  1767.  
  1768.     error=WriteString(net,string)
  1769.                       a0  a1
  1770.  
  1771.     ULONG WriteString(APTR,STRPTR);
  1772.  
  1773.  
  1774. FUNCTION
  1775.     This function is pretty similar to WriteNet(). In fact this function
  1776.     is just a pre-function to WriteNet(). It counts the number of chars in
  1777.     the string until zero is found and the calls the WriteNet() function with
  1778.     length as parameter. Read about WriteNet() for more info.
  1779.  
  1780.     The result code is actually returned be WriteNet() and reflects the
  1781.     io_error field. Null if ok.
  1782.  
  1783. INPUTS
  1784.     net - ptr. to a valid net structure
  1785.     string - ptr. to a null-terminated string
  1786.  
  1787. RESULTS 
  1788.     error - reflects the io_error field. Null if ok.
  1789.  
  1790. NOTES
  1791.     
  1792. EXAMPLE
  1793.     
  1794. BUGS
  1795.     
  1796. SEE ALSO
  1797.     ReadString()
  1798.  
  1799. dignet.library/RTAbort                                 dignet.library/RTAbort
  1800.  
  1801. NAME
  1802.     RTAbort -- Tries to abort an allocated  net (version 3)
  1803.  
  1804. SYNOPSIS
  1805.  
  1806.     RTAbort(ID)
  1807.             d0
  1808.  
  1809.     void RTAbort(ULONG);
  1810.  
  1811.  
  1812. FUNCTION
  1813.     This function will try to abort a net. If the net isn't in use the
  1814.     function will return immediatly. There is no saftcheck on the pointers.
  1815.  
  1816. INPUTS
  1817.     ID - ID of a net
  1818.  
  1819. NOTES
  1820.     
  1821. EXAMPLE
  1822.     
  1823. BUGS
  1824.     
  1825. SEE ALSO
  1826.    RTNetInfo
  1827.  
  1828. dignet.library/RTCheck                                 dignet.library/RTCheck
  1829.  
  1830. NAME
  1831.     RTCheck -- Checks the count list for mismatch (version 3)
  1832.  
  1833. SYNOPSIS
  1834.  
  1835.     status=RTCheck()
  1836.  
  1837.  
  1838.     BOOL RTCheck(void);
  1839.  
  1840.  
  1841. FUNCTION
  1842.     This function check the resource tracklist and the opennet counter for
  1843.     any mismatch. If this function return FALSE there is a mismatch in the
  1844.     count lists. That could mean some net isn't properly killed (invalid
  1845.     pointer was given to RTKillNet() or something like that). If there is a
  1846.     mismatch you have to cleanup manually by finding the net that should be
  1847.     killed and then FreeNet() it. You do so at your own risk!
  1848.  
  1849. RESULTS 
  1850.     status - TRUE if ok, otherwise FALSE and system is in risk.
  1851.  
  1852. NOTES
  1853.     
  1854. EXAMPLE
  1855.     
  1856. BUGS
  1857.     
  1858. SEE ALSO
  1859.     RTNumberofNets()
  1860.  
  1861. dignet.library/RTFlush                                  dignet.library/RTFlush
  1862.  
  1863. NAME
  1864.     RTFlush -- Tries to flush an allocated net (version 3)
  1865.  
  1866. SYNOPSIS
  1867.  
  1868.     RTFlush(ID)
  1869.                d0
  1870.  
  1871.     void RTFlush(ULONG);
  1872.  
  1873.  
  1874. FUNCTION
  1875.     This function will try to flush an allocated net. You should check for
  1876.     the existance of the net by using the RTNetInfo() function first.
  1877.  
  1878. INPUTS
  1879.     ID - ID of a net
  1880.  
  1881. NOTES
  1882.     
  1883. EXAMPLE
  1884.     
  1885. BUGS
  1886.     
  1887. SEE ALSO
  1888.     RTNetInfo()
  1889.  
  1890.  
  1891. dignet.library/RTHighestID                         dignet.library/RTHighestID
  1892.  
  1893. NAME
  1894.     RTHighestID -- Return the highest ID number (version 3)
  1895.  
  1896. SYNOPSIS
  1897.  
  1898.     HighestID=RTHighestID()
  1899.  
  1900.  
  1901.     ULONG RTHighestID(void);
  1902.  
  1903.  
  1904. FUNCTION
  1905.     This function will return the highest ID number available. If there are
  1906.     no nets if will return NULL. This function is useful when you will parse
  1907.     a list.
  1908.  
  1909. RESULTS 
  1910.     HighestID - highest ID number or NULL if no nets are allocated
  1911.  
  1912. NOTES
  1913.     
  1914. EXAMPLE
  1915.     
  1916. BUGS
  1917.     
  1918. SEE ALSO
  1919.     RTNetInfo()
  1920.  
  1921. dignet.library/RTKillNet                             dignet.library/RTKillNet
  1922.  
  1923. NAME
  1924.     RTKillNet -- Tryes to kill an allocated net (version 3)
  1925.  
  1926. SYNOPSIS
  1927.  
  1928.     RTKillNet(ID)
  1929.               d0
  1930.  
  1931.     void RTKillNet(ULONG);
  1932.  
  1933.  
  1934. FUNCTION
  1935.     This function will try to kill an allocated net. You should however use
  1936.     the function RTNetInfo() first to check if the netowener task is in
  1937.     tasklist or not. You shouldn't kill a net that is owned by a healthy
  1938.     task.
  1939.  
  1940.     If the net ID isn't valid the function will return immediatly.
  1941.  
  1942. INPUTS
  1943.     ID - Net ID.
  1944.  
  1945. NOTES
  1946.     DO NOT use this function on a healthy task!
  1947.  
  1948. EXAMPLE
  1949.     
  1950. BUGS
  1951.     
  1952. SEE ALSO
  1953.     RTNetInfo(), RTAbort(), RTFlush()
  1954.  
  1955. dignet.library/RTNetInfo                             dignet.library/RTNetInfo
  1956.  
  1957. NAME
  1958.     RTNetInfo -- Returns vital information about a net ID (version 3)
  1959.  
  1960. SYNOPSIS
  1961.  
  1962.     success=RTNetInfo(buffer,ID)
  1963.                       a0     d0
  1964.  
  1965.     BOOL RTNetInfo(APTR,ULONG);
  1966.  
  1967.  
  1968. FUNCTION
  1969.     This function will copy vital information from the private RT structure
  1970.     in the library to a public structure (see dignet/dignet.i|h). If the net
  1971.     ID isn't valid (eg. isn't used) the function will return immediatly with
  1972.     FALSE in bool.
  1973.  
  1974. INPUTS
  1975.     buffer - ptr. to a buffer that contains the structure (DNRT_SIZEOF)
  1976.     ID - net ID to get info about
  1977.  
  1978. RESULTS 
  1979.     success - TRUE (-1) if success, otherwise FALSE
  1980.  
  1981. NOTES
  1982.     
  1983. EXAMPLE
  1984.     
  1985. BUGS
  1986.     
  1987. SEE ALSO
  1988.     RTHighestID(), RTNumberofNets(), dignet/dignet.i|h
  1989.  
  1990. dignet.library/RTNumberofNets                   dignet.library/RTNumberofNets
  1991.  
  1992. NAME
  1993.     RTNumberofNets -- Returns number of open nets (version 3)
  1994.  
  1995. SYNOPSIS
  1996.  
  1997.     number=RTNumberofNets()
  1998.  
  1999.  
  2000.     ULONG RTNumberofNets(void);
  2001.  
  2002.  
  2003. FUNCTION
  2004.     This function will return number of open nets in the system. You should
  2005.     use the RTCheck to find out any mismatch in the net count and resource
  2006.     trackers counter.
  2007.  
  2008. RESULTS 
  2009.     number - number of nets open
  2010.  
  2011. NOTES
  2012.     This function doesn't return the highest available number of nets. Use
  2013.     the function RTHighestID() to find that out.
  2014.  
  2015. EXAMPLE
  2016.     
  2017. BUGS
  2018.     
  2019. SEE ALSO
  2020.     RTCheck(), RTHighestID()
  2021.